home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / utility / base64_5.zip / BASE64.TXT next >
Text File  |  1996-08-21  |  19KB  |  447 lines
  1. Documentation for the Base-64 Encoder:
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3.  
  4. Contents:
  5. ~~~~~~~~~
  6.  
  7. 1. General information regarding the programs
  8. 2. About ENCODE64.EXE   
  9. 3. About DECODE64.EXE    
  10. 4. About UNIX2DOS.COM
  11. 5. Technical information regarding BASE-64 encoding
  12. 6. Disclaimer, Distribution, About the Author, etc. 
  13. 7. Registration Information (Read this!)
  14. 8. Revision Notes
  15.  
  16. For information on SHELL64.EXE, refer to SHELL64.TXT.
  17. Please register!
  18.  
  19.  
  20. 1. General:
  21. ~~~~~~~~~~~
  22.   These DOS programs have built-in error checking to make sure the files
  23. are processed correctly. However, if there are unexplained errors while
  24. processing, the program will give a "Runtime Error" message. Check in
  25. this documentation for information regarding possible errors. Most errors
  26. will likely be caused by the DECODE64 program, because of text-processing
  27. problems. If all else fails, refer to the section on DECODE64 and see
  28. how the program works! If you think a certain problem may be a bug in 
  29. the program, please e-mail me. My e-mail address is at the bottom of 
  30. this document.
  31.  
  32.   NOTE: DECODE64 will ONLY decode files with a CR/LF at the end of every
  33. line, so it will not decode UNIX text files. A utility I wrote was included
  34. with these programs, called UNIX2DOS. See the section on UNIX2DOS.COM for
  35. information on how to use it.
  36.   
  37.   REGARDING E-MAIL: Internet mail programs will probably not recognize 
  38. encoded files over e-mail when encoded using ENCODE64. This is because 
  39. information is added to the header and body of sent e-mails when files 
  40. are included with them. It is impossible to mimic this with these 
  41. programs. Whoever receives a Base64 encoded file encoded using ENCODE64 
  42. may need a utility similar to DECODE64 to be able to decode it. (This 
  43. is especially true when using multiple-part encoding & decoding.)
  44.  
  45.  
  46. 2. About ENCODE64.EXE:
  47. ~~~~~~~~~~~~~~~~~~~~~~
  48.   This program takes any file (binary or otherwise) and converts it 
  49. into a format transmittable over the Internet. (See technical information 
  50. below.) The command line for this program is:
  51.  
  52. ENCODE64 <input filename> [output filename] [/M<number>] [/O] [/P]
  53.  
  54. Items in <> are necessary, in [] are optional.
  55.  
  56. Where <filename> is any file. [Output filename] is optional, but if you
  57. do give it, ENCODE64 will attempt to use that file name instead of the
  58. generic ".64" filename. 
  59.  
  60. The "/O" option was added for compatibility purposes. When you use this
  61. option, the program will AUTOMATICALLY attempt to overwrite any files
  62. it needs to, without having a (Y/N) prompt. Use this carefully.
  63.  
  64. The "/M" option tells ENCODE64 to do a multiple-file output. A number
  65. should immediately follow, telling ENCODE64 how many kilobytes (KB) of 
  66. data should be put into each file. 1 kilobyte is slightly less than 
  67. 20 lines of data. The program will tell you if the number of kilobytes you 
  68. specified is too out of range for the particular file you are encoding. 
  69. The maximum number of files ENCODE64 will output to is 99 (for filename 
  70. reasons).
  71.  
  72. The "/P" option will turn on a percentage meter which tells how far
  73. through ENCODE64 is. For single files, it will show how far it is
  74. so far. For multiple files, it will show how far through it is for
  75. the particular file it is working on. (The last file it creates may
  76. not reach 100%)
  77.  
  78. Examples:
  79.  
  80. C:\>ENCODE64 PROGRAM.ZIP
  81.  
  82. After executing this, ENCODE64 will create a file called "PROGRAM.64" in
  83. the current directory. If a file with that name was already found, it will
  84. say so and will not overwrite it (it must be moved or deleted before
  85. ENCODE64 will create the file, just to make sure that no data is lost).
  86.  
  87. C:\>ENCODE64 PROGRAM.ZIP PROG.TXT
  88.  
  89. ENCODE64 will attempt to make a file called PROG.TXT instead of the
  90. generic PROGRAM.64. It will ask you if you wish to overwrite it if
  91. it already exists.
  92.  
  93. C:\>ENCODE64 PROGRAM.ZIP PROG.TXT /M20 /O /P
  94.  
  95. ENCODE64 will attempt to make multiple files until the end of PROGRAM.ZIP
  96. is reached. It will start with PROG01.TXT, put 20 kilobytes of encoded data
  97. in it (approx. 400 lines of data), then move on to PROG02.TXT. If it 
  98. encountered PROG01.TXT already, it will automatically overwrite it because 
  99. the "/O" option was put on the command line. It will also have a percentage
  100. meter which will show how far it is through each one of the files it
  101. creates.
  102.  
  103.  
  104. 3. About DECODE64.EXE:
  105. ~~~~~~~~~~~~~~~~~~~~~~
  106. Command line for this program is:
  107.  
  108. DECODE64 <input file/file mask> [output file] [/M] [/O] [/K] [/L]
  109.  
  110. Items in <> are necessary, in [] are optional.
  111.  
  112. Where <input filename> is any Base64-encoded file.
  113.  
  114. The "/O" option tells DECODE64 to automatically erase any files it needs
  115. to without prompting you. Be careful when using this switch that you
  116. do not overwrite any important files.
  117.     
  118. With the "/K" option, DECODE64 will continue reading through a Base64-
  119. encoded file until all files are decoded out of it. This is useful
  120. for messages where more than one file is sent. After finishing the
  121. first file, it will look for the 'name="' or 'name = ' strings over
  122. and over again until it doesn't find any more.
  123.  
  124. If you supply an [output filename], DECODE64 will use that instead
  125. of the filename it finds inside the Base64-encoded file(s). When
  126. using the "/M" option, DECODE64 will use the filename it finds in the
  127. first Base64-encoded file it scans.
  128.  
  129. The "/M" option tells the program to accept input from more than one
  130. file. If you use this, you should use a <filename mask> instead of a
  131. single <input filename>. The mask should use generic DOS wildcard
  132. characters such as '*' and '?'. Use the "DIR" command to make sure
  133. the files are in the correct order before decoding. (See examples below.)
  134.  
  135. The "/L" option tells DECODE64 to decode multiple encoded files, one
  136. at a time, using a <file mask>. This does not work with "/M". The 
  137. [output file] option does not work with this. "/K" is automatically 
  138. activated by the program when this switch is used, meaning that only
  139. the first file located in each encoded file will be decoded, and 
  140. decoding will stop in each file as soon as the first file is finished.
  141. (See examples below)
  142.  
  143. At the top of every multiple-part file created by ENCODE64, it tells what 
  144. part number the current file is, and how many parts there are totally.
  145. This first number can be used to create the correct filename for decoding
  146. multiple-part files, if you receive them in different e-mails. (Otherwise
  147. there may not be a way to tell which file comes first, second, etc.) Note
  148. that DECODE64 is *not* able to read this header automatically, since it
  149. does not know which files are made with which encoder.
  150.  
  151. DECODE64 will automatically right- and left-justify all lines of encoded
  152. data.
  153.  
  154. Examples:
  155.  
  156. C:\>DECODE64 PROGRAM.64 PROG.ZIP
  157.  
  158. Running it with this command line will make DECODE64 attempt to
  159. decode PROGRAM.64, and, instead of using the file name it finds in
  160. PROGRAM.64, it will use the filename PROG.ZIP to output to.
  161.  
  162.  
  163. C:\>DECODE64 PROGRAM.64 PROG.ZIP /O
  164.  
  165. If PROG.ZIP already exists, DECODE64 will erase it without prompting.
  166.  
  167.  
  168. C:\>DECODE64 PROG*.64 PROG.ZIP /M /O
  169.  
  170. DECODE64 will use the filename mask "PROG*.64" and use those files to
  171. output to PROG.ZIP. DECODE64 will discard whatever filename it finds
  172. in the PROG*.64 files, and use the name "PROG.ZIP" instead. If PROG.ZIP
  173. already exists, DECODE64 will erase it without prompting. Be careful
  174. when using the /M option -- use "DIR" before running DECODE64 to make
  175. sure your files are in the correct order. Such as:
  176.  
  177. PROG01.64
  178. PROG02.64
  179. PROG03.64
  180.    ...
  181.  
  182. This would be ideal. This is the order that ENCODE64 puts files in.
  183.  
  184.  
  185. C:\>DECODE64 *.64 /L
  186.  
  187. This would decode all files with the ".64" extension, one at a time.
  188.  
  189.  
  190. The ideal format for the BASE 64 file would be one created by the 
  191. ENCODE64 program, or in this format:
  192.  
  193. --==========================
  194. name="test.zip"
  195. <header stuff>
  196. <header stuff>
  197.  
  198. AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHHIIIIJJJJKKKKLLLLMMMMNNNNOOOOPPPP
  199. QQ==
  200. --==========================
  201.  
  202. Note the blank line between the header and the encoded data, and the
  203. "-" char